home *** CD-ROM | disk | FTP | other *** search
% If you somehow got this file without fullpage.sty, delete % ``fullpage'' from the list of style options. It just pulls out the % margins a bit. \documentstyle[11pt,twoside,fullpage]{report} % New commands %------------- % for meta-symbols \newcommand{\meta}[1]{{\bf \mbox{\(<\)#1\(>\)}}} % for literal tokens. \newcommand{\lit}[1]{{\tt \mbox{#1}}} %for attributes \newcommand{\atr}[1]{\mbox{\sc #1}} % for identifying text \newcommand{\text}[1]{{\em #1}\/} % Start and end of One or More \newcommand{\ooms}{\([\,\)} \newcommand{\oome}{\(\,]^+\)} % start and end of zero or more \newcommand{\zoms}{\([\,\)} \newcommand{\zome}{\(\,]^*\)} % Start and end of zero or one \newcommand{\zoos}{\([\,\)} \newcommand{\zooe}{\(\,]\)} % start an OR \newcommand{\ors}{{\bf (\,}} \newcommand{\ore}{{\bf \,) }} \newcommand{\metaor}{{\em \,or\, }} \newcommand{\hexnum}[1]{\(\mbox{#1}_{16}\)} \newcommand{\unix}{{\sc unix}} \newcommand{\selectlines}{\zoms\meta{LF} \\ \lit{SELECT} \meta{applies-to} \ors\lit{FIELD} \metaor \lit{INTRINSIC} \metaor \lit{APPLICATION}\ore \meta{attribute-name} \meta{attribute-value-type}\ore \zoms\meta{value-tuple-element}\zome\zome} \newenvironment{command}{\begin{verse}\sloppy}{\end{verse}} \newcommand{\commandsize}{\large} %\newtheorem{example}{Example} % Uncomment this for almost-double spacing %\renewcommand{\baselinestretch}{1.7} %\newcommand{\hozline}{\rule{\textwidth}{0.3mm}} %\newcommand{\hozline}{\makebox[\textwidth]{\hrulefill}} %\newcommand{\bex}{\begin{example} \begin{rm}} %\newcommand{\eex}{$\Box$ \end{rm} \end{example}} %\newcommand{\cbs}{\chgbarbegin} %\newcommand{\cbe}{\chgbarend} %\newcommand{\cbs}{} %\newcommand{\cbe}{} %\newcommand{\ptag}{\begin{flushright} {\rm ($P$)} \end{flushright} } \begin{document} \pagenumbering{arabic} \pagestyle{plain} \renewcommand{\thepage}{\arabic{page}} %\title{The Prospero Protocol, version 5\thanks{ % This research was supported in part by the National Science % Foundation (Grant No. CCR-8619663), the Washington Technology Center, % Digital Equipment Corporation, and the Defense Advanced Research % Projects Agency under NASA Cooperative Agreement NCC-2-539} %\author{B. Clifford Neuman\thanks{ % To Contact the Authors: \protect\\ %Electronic Mail: \protect\mbox{\protect\verb"info-prospero@isi.edu"} \\ % Telephone: +1 (310) 822-1511 \protect\\ % Mail: USC Information Sciences Institute \\ % 4676 Admiralty Way \\ % Marina del Rey, California 90292--6695 U.S.A. } % \and Steven Seger Augart %\and Information Sciences Institute \\ % University of Southern California %\date{ %\maketitle \begin{titlepage} \renewcommand{\thefootnote}{} \footnotetext{\hspace*{-21pt} Digital copies of the latest revision of this document may be obtained through Prospero as \mbox{\verb"/papers/subjects/operating-systems/prospero/doc/protocol.PS.Z"}, in the \mbox{\tt \#/INET/EDU/ISI/swa} virtual system, or through Anonymous FTP from \mbox{\tt PROSPERO.ISI.EDU} as \mbox{\verb"/pub/prospero/doc/prospero-protocol.PS.Z"} \footnotetext{\hspace*{-21pt} This work was supported in part by the National Science Foundation (Grant No. CCR-8619663), the Washington Technology Center, Digital Equipment Corporation, and the Defense Advance Research Projects Agency under NASA Cooperative Agreement NCC-2-539. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of any of the funding agencies. The authors may be reached at USC/ISI, 4676 Admiralty Way, Marina del Rey, California\ \ 90292-6695, USA. Telephone +1 (310) 822-1511, email \mbox{\verb"info-prospero@isi.edu"}. } \renewcommand{\thefootnote}{\arabic{footnote}} \vspace*{\fill} \begin{center} \LARGE The Prospero Protocol\\ \Large Version 5\\ \vskip 1.5em {\large Draft of 12 June 1993} \\ {\large Document Revision No. 0.3} \\ \end{center} \vspace{.5in} \Large \hspace*{\fill} B. Clifford Neuman %\footnotetext{\hspace*{-18pt} % To Contact the Authors: \\ % Electronic Mail: \mbox{\verb"info-prospero@isi.edu"} \\ % Telephone: +1 (310) 822-1511 \\ % Mail: USC Information Sciences Institute, 4676 Admiralty Way, % Marina del Rey, California 90292--6695\ \ U.S.A. \hfill Steven Seger Augart \hspace*{\fill} \\ \vspace{.2in} \begin{center} \Large Information Sciences Institute \\ University of Southern California \end{center} \vspace*{1.2in} \vspace*{\fill} \end{titlepage} \tableofcontents \chapter{Introduction} This document describes version 5 of the Prospero protocol. Communication with directory servers uses a reliable delivery protocol described in Appendix~\ref{ardp}. Requests and responses are human readable commands and multiple commands may be sent in a single message. Prospero is implemented on top of a message-based protocol to reduce the overhead that would otherwise be incurred when establishing connections to multiple directory servers. The decision to use a message protocol directly, instead of through a higher level mechanism such as remote procedure call, was made for reasons of portability. We did not want Prospero to depend on another protocol, software package, or other resource, unless that resource was almost universally supported by every computer on the Internet. The use of humanly readable commands in the protocol has several advantages. It eliminates problems with byte ordering, and it makes future changes or additions to the protocol easier to incorporate while maintaining compatibility across versions; new commands or additional options to existing commands can be easily added. The ability to request multiple operations in a single message improves performance, and it provides a simple way to request that a collection of operations (on a single server) be performed atomically. The concept of an ``attribute'' appears frequently in the following command description. For a discussion of attributes, read appendix~\ref{db} of this document. \section{Additional Documents} The Prospero documentation series will include the following: \begin{description} \item[Prospero Protocol Specification] You're reading it. Right now, this is the most current document we have, but it will eventually be re-targeted towards a more specialized audience when the other guides in the series are written and revised. \item[Prospero System User's Guide] This will describe the general features of the Prospero system that will be common to almost all user interfaces, such as ACL types and filters. \item[Prospero Command-Line Client User's Guide] Describes the command-line client package; this is the client that's been shipped with all Prospero releases. \item[Prospero Gopher Client User's Guide] This describes the Gopher menu-based client package, which is in progress. %\item[Prospero World-Wide Web Client User's Guide] This describes the %World-Wide Web hypertext client package, which hasn't yet been written %but is going to be done Real Soon Now. \item[Prospero Programmer's Manual] This describes the \lit{pfs} and \lit{pcompat} libraries, which Prospero applications programmers use to interface with Prospero. \end{description} \chapter{Command Introduction} \section{Spaces, quoting, and line-feeds} Prospero messages are divided into lines. Lines are divided into tokens. Commands and lines sent in response are separated by an unquoted {\sc ASCII} \meta{LF} character. Within a line, tokens are separated by unquoted horizontal whitespace (one or more {\sc ASCII} spaces and/or tabs). Client and server implementations are not required to accept lines which begin or end with horizontal whitespace, but are encouraged to do so. Similarly, implementations are encouraged to accept \meta{CR} or \meta{CR}\meta{LF} as alternative acceptable line terminators, but are not required to do so. % ``Be conservative in what you send, generous %in what you accept.'' (J. Postel) Special characters within a command token, or null tokens, can be quoted using single quotes (\lit{'}). While inside quotes, a quote can be included by doubling it. The only character that cannot be quoted is the ASCII null character (character code zero; \verb"'\0'" for C programmers). This is really a limitation of the server implementation, which passes Prospero packets, commands, and tokens around internally as null-terminated C strings.\footnote{If you wish to send binary data around, we recommend that you encode it into a null-less form using the \lit{pfs} library's \lit{binencode()} and \lit{bindecode()} routines.} Any token may be quoted (although most will not need quoting), except for literal command tokens (\lit{VERSION}, \lit{ID}, etc.). Also, the \meta{multi-component} token uses the quoting system in a special way --- see the \lit{LIST} command for details. \section{Options} Many Prospero Protocol commands take options. If multiple options are to be specified for a single command, the options are separated by a ``\lit{+}''. If no options are specified, then the null string should be sent to indicate this. The null string will need to be quoted, like so: \lit{'{}'} \section{Metasyntax} In this document, we will use some meta-syntactic features to describe commands. Literal tokens (such as \lit{LITERAL-TOKEN}) appear in a typewriter font. Non-terminals look like this: \meta{non-terminal}. The line-feed, carriage-return, and space characters are represented as \meta{LF}, \meta{CR}, and \meta{SPC}, respectively. Alternation (choice among two or more possibilities) looks like: \ors\meta{option1} \metaor \meta{option2} \ore We also use the following meta-syntactic constructs: %\begin{table}[htb] \begin{center} \begin{tabular}{|c|c|l|} \hline \multicolumn{3}{|c|}{Metasyntax used to describe commands} \\ \hline Start & End & \multicolumn{1}{c|}{Meaning} \\ \hline [ & ] & One or zero repetitions. \\ \hline [ & \(]^*\) & Zero or more repetitions. \\ \hline [ & \(]^+\) & One repetition or more. \\ \hline \end{tabular} \end{center} %\end{table} \section{Objects} A Prospero object is anything to which a normal link (\meta{link-type} = \lit{L}) can be made, except for \lit{EXTERNAL} objects. \subsection{Base Type\label{base type}} Every Prospero object has one or more base types associated with it. All Prospero objects have a base type of OBJECT. This means that they can have attributes attached to them. In addition, objects with a base type of FILE can store data, and objects with a base type of DIRECTORY can store directory information. \begin{sloppypar} The base type of a Prospero object is accessible through the \atr{base-type} intrinsic attribute. The primitive value for \atr{base-type} is \lit{OBJECT}. If an object's \atr{base-type} attribute has a value of %\linebreak[3] \lit{OBJECT+FILE+DIRECTORY}, then the object can have attributes attached to it, can contain data, and can contain links. As a shorthand, since all objects have \lit{OBJECT} as one of their base types, an object with more than one base type can have the \lit{OBJECT} implied, so that the \atr{base-type} value \lit{OBJECT+FILE+DIRECTORY} is equivalent to the value \lit{FILE+DIRECTORY} and the value \lit{FILE} is equivalent to the value \lit{FILE+OBJECT}. The order of values in the \atr{base-type} attribute is unimportant, so \lit{DIRECTORY+FILE} is equivalent to \lit{FILE+DIRECTORY}. \end{sloppypar} In the rest of this document, when we say ``directory,'', we mean ``an object which has \lit{DIRECTORY} as part of its \atr{base-type}.'' When we say ``file,'' we mean ``an object which has \lit{FILE} as part of its \atr{base-type}.'' One may use \lit{EDIT-OBJECT-INFO} to edit the \atr{base-type} attribute to remove the \lit{FILE} type from it only if the file is empty (zero length), and one may remove the \lit{DIRECTORY} type from it only if the directory is empty (contains no links). To add a type to the \atr{base-type}, one must use the \lit{ADD} option to \lit{CREATE-OBJECT}. \subsection{Host-Specific Object Names ({\sc hsoname}s)} Every Prospero object has an \meta{hsoname}. {\sc hsoname}s are not guaranteed to be unique across time; if an object is deleted, a new object may be created that re-uses the old object's handle. However, at any particular moment, two Prospero objects on the same server are guaranteed to have unique hsonames, unless they are different versions of the same object (i.e., unless their \atr{version-number} fields are different.) Two objects on different servers might have identical hsonames. In the current server implementation, the \meta{hsoname-type} is always \lit{ASCII} and the \meta{hsoname} is almost always a full (i.e., starting with a slash (\lit{/})) \unix\ filesystem pathname. See appendix~\ref{conventions} for more discussion of this. The \meta{hsoname-type} token exists because some special filesystems may have non-\lit{ASCII} \meta{hsoname}s. \subsection{Versions\label{object version numbers}} We intend to allow versioned objects. All objects, including directories, have a \atr{version-number} field. In the current server implementation, the \atr{version-number} field is always zero, which means ``unversioned''. It need not be in future server implementations. In commands and responses, providing a zero value for the \meta{object-version} token means to retrieve the current version of the object. Specifying explicit values means that a particular version of the object is required. Explicit object version numbers (when they are established) will always be positive integers. \subsection{Object \lit{ID} fields} The \lit{ID} field is a unique (or nearly unique) identifier for an object. If the underlying object changes (such as by editing), then some types of \lit{ID}s will change and others will not. If two objects have the same \lit{ID}, then they are considered by Prospero to be the same object. This is useful for distinguishing between two cases: (a) two links which happen to have the same \meta{name-component} but different storage locations (a different host and handle pair), and which do not actually represent the same object, and (b) two links which have the same \meta{name-component} and same \lit{ID}, but possibly different storage locations --- in case (b), the objects are replicas and the client should access whichever one it chooses to. (Code is currently under development to enable servers to return a list of replicas in order of nearness to the client.) Two links with the same \meta{name-component} and no \lit{ID} specification are considered by Prospero to be different objects, not replicas of one another. A problem with the \lit{ID} field is that there is not an accepted standard for universal document identifiers. An IETF working group has been formed to consider such identifiers, and the \lit{ID} field exists in anticipation of their eventual agreement upon a standard. We expect that there will be more than one type of universal document identifier; therefore, there will be more than one \meta{id-type}. Prospero supports objects with several possible \lit{ID}s.% \footnote{This will go into the user's manual when we revise it. The user-level names for two links distinguished only by their \lit{ID} fields are: \begin{command} \ors\meta{name-component}\lit{\#}\lit{\#}\(\mbox{\meta{id-type}}_1\)\lit{\#}\(\mbox{\meta{id-value-token}}_{1,1}\)\lit{\#}\(\mbox{\meta{id-value-token}}_{1,2}\)\ldots % permit a line break here \lit{\#}\lit{\#}\(\mbox{\meta{id-type}}_2\)\lit{\#}\(\mbox{\meta{id-value-token}}_{2,1}\)\lit{\#}\(\mbox{\meta{id-value-token}}_{2,2}\)\ldots \\ \metaor \meta{name-component}\lit{\#}\(\mbox{\meta{id-value-token}}_1\)\lit{\#}\meta{id-value-token$_2$}\ldots \ore \end{command} The second form matches any \meta{id-type}. The first form is used to explicitly specify one or more \meta{id-type}s. For now, there are only two \meta{id-type}s defined. The \lit{REMOTE} \meta{id-type} is used by the server when it has magic knowledge (perhaps through a local database) that two objects are the same. The \lit{REMOTE} id type is a single element which is the printed decimal representation of a positive integer. This positive integer should be able to be stored in a 32 bit integer. A \lit{REMOTE} id value of 0 means ``unspecified''. The \lit{REMOTE} \meta{id-type} cannot be sent across the network by clients in queries.% \footnote{The \meta{id-value} of the \lit{REMOTE} type is the same as the \meta{magic-no} token specified in version 1 of the Prospero protocol.} It is not guaranteed to be consistent across different queries to the server, but server implementors are encouraged to make the \meta{id-value} token consistent across queries. Many clients will locally generate \lit{ID} fields to help the human user differentiate between conflicting links. These \lit{ID} fields will have an \meta{id-type} of \lit{LOCAL} and an arbitrarily generated string as their \meta{id-value}. They may not be sent over the network, and are not guaranteed to be unique from directory read to directory read, although implementors are encouraged to make them so. All available \lit{ID} fields will be returned with every \lit{LIST} operation. \chapter{Commands Reference} All Prospero commands are listed below. \section{VERSION} \begin{command} \commandsize \lit{VERSION} \meta{version-number} \zoos\meta{software-identifier}\zooe \end{command} This command requests or specifies the protocol version number. If the specified protocol version number is not supported, the response will be: \begin{command} \lit{VERSION-NOT-SUPPORTED TRY} \meta{min-version-number}\lit{-}\meta{max-version-number} \end{command} \begin{command} \lit{VERSION-NOT-SUPPORTED TRY} \meta{version-number} \end{command} Where \meta{version-number} or \meta{min-version-number}\lit{-}\meta{max-version-number} are those versions that are supported. If no arguments are supplied (or if the argument is not a number), then the \lit{VERSION} command will return the current protocol version number being used by the server in the form: \begin{command} \lit{VERSION} \meta{version-number} \zoos\meta{software-identifier}\zooe \end{command} If the \meta{software-identifier} is specified, it identifies the software and version of the software that is generating the message.\footnote{Software developers wishing to obtain software identifiers should send electronic mail to {\tt pfs-administrator@isi.edu}.} \section{AUTHENTICATE} \begin{command} \commandsize \lit{AUTHENTICATE} \meta{options} \meta{authenticator-type} \meta{authentication-data} \zoms\meta{principal-name}\zome \end{command} This command authenticates the principal making the request. The \meta{authenticator-type} is the type of the authenticator. It might be a password, a Kerberos authenticator, or data used by an alternative authentication mechanism. The currently supported values for \meta{authenticator-type} are \lit{UNAUTHENTICATED}, \lit{KERBEROS}, and \lit{HANDLE}. If the \meta{authenticator-type} is \lit{UNAUTHENTICATED}, this is honored by the \lit{ASRTHOST} ACL type. It is also honored by the \lit{TRSTHOST} ACL type if the client is using a privileged port. If the \meta{authenticator-type} is \lit{UNAUTHENTICATED}, then the \meta{authentication-data} should be the username of the user running the client. This username is be the principal referred to by the ACL. If the \meta{authenticator-type} is \lit{KERBEROS}, then the \meta{authentication-data} is a Kerberos authentication message authenticating the principal to the Prospero server. The ACL principal will be the same as the Kerberos principal. The ACL type will be \lit{AUTHENT} \lit{KERBEROS}. If the \meta{authenticator-type} is \lit{HANDLE}, then the \meta{authentication-data} is a handle returned in response to a previous \lit{AUTHENTICATE} command. The optional \meta{principal-name}s are informational only for some authentication types, and exist only for human convenience. The server will extract the principal names from the \meta{authentication-data}, but the names might be encrypted in the \meta{authentication-data} or otherwise represented in a way that humans cannot easily decipher them. (For instance, this is the case with Kerberos version 5.) In the case of the \lit{P\_PASSWORD} authentication type, the \meta{principal-name}s are not optional. More than one \lit{AUTHENTICATE} command may be sent in a single message. This can be used both to authenticate oneself as multiple simultaneous principals and to authenticate oneself using several methods. The response may take one of several forms. If the authentication fails, then the response is: \begin{command} \lit{FAILURE} \lit{AUTHENTICATION-DATA} \zoos\text{explanatory text}\zooe \end{command} One might get this response if an authentication handle has expired. If it is computationally expensive for the server to validate the authentication data, it may want to cache the fact that the data has been validated, and return a handle that the client may use in future requests to the server: \begin{command} \lit{AUTHENTICATED} \zoos\meta{authentication-handle} \zoos\meta{handle-expiration-time}\zooe \zooe \end{command} The \meta{handle-expiration-time}, if provided, is in ASN-TIME format. The response may be another \lit {AUTHENTICATE} command if the server needs to authenticate itself to the client.\footnote{XXX: Not currently implemented.} The response may simply be: \begin{command} \lit{AUTHENTICATED} \end{command} to indicate that the authentication succeeded. If other commands are included in the same packet as the \lit{AUTHENTICATE} request (this will almost always be the case), then successful execution of theose other commands implies that the authentication succeeded; in this case, the server is not required to include the \lit{AUTHENTICATED} response. Currently, no options are defined, so the \meta{options} token is always the null string. \section{DIRECTORY} \begin{command} \commandsize \lit{DIRECTORY} \meta{hsoname-type} \meta{hsoname} \zoos\meta{object-version}\zooe \selectlines \end{command} This command specifies the directory to be read or modified by the commands that follow as part of the same request. This command does not generate a response unless the selected directory is not a directory. In that case, the response: \begin{command} \lit{FAILURE NOT-A-DIRECTORY} \end{command} is returned, and the remainder of the request ignored. \section{ATOMIC} \begin{command} \commandsize \lit{ATOMIC} \end{command} This command specifies that all commands that follow are to be completed atomically. If one of the commands fails, then none of the commands are to have an effect. This may require undoing the effects of commands which have already completed. Note that this command works only for requests issued in the same message, and all commands must be executable on the single server to which the message was sent. This command is not currently implemented. \section{LIST} \begin{command} \commandsize \lit{LIST} \meta{options} \lit{COMPONENTS} \zoms\meta{name-component}\zome\selectlines\meta{LF}\\ \lit{FILTER} ... \end{command} \lit{LIST} is used to look up information stored in a directory. It must be preceded by a \lit{DIRECTORY} command in the same request. Each optional \meta{name-component} is a component of a multiple-component name relative to the directory specified in the \lit{DIRECTORY} command. The last component may include wildcards. If no \meta{name-component} is specified, the wildcard ``*'' is implied (i.e., all listable components in the directory will be listed).\footnote{ The protocol is currently in transition. The old format was as follows: Multiple component names are allowed, and are specified as a single token following the \meta{name-component}. The multiple components within a single name are separated by the unquoted slash (\lit{/}). Servers and clients for now are accepting both versions of the protocol message, which means that the 1st component of a multiple-component name must be quoted if it contains a slash.} If the result of the lookup of one component is another directory at the same storage site, then the directory server will repeat the process and look up the next component. When a lookup results in a dead-end, or a directory at another site, the server will return an \lit{UNRESOLVED} message, indicating which components remain to be resolved by the client. If a space, tab, slash, or \meta{LF} is to be included in a component of a single-component or multi-component name, the component must be quoted. Quoting a slash in a single-component or multi-component name means that the slash is not considered to separate components of a multi-component name, but rather to be a part of a single component. This somewhat awkward syntax allows us to have single components which contain slashes or horizontal whitespace or \meta{LF}s. \subsection{Wildcards} The \meta{name} tokens in the \lit{LIST} command are the only places in the Prospero protocol where components may be specified with wildcards. There are two wildcard characters supported: \begin{description} \item[\lit{*}] Match zero or more characters. \item[\lit{?}] Match exactly one character. \end{description} Wildcards may only be used to expand at a single-component level; by this, we mean that the wildcarded \meta{name} \lit{foo?bar} would match the single-component name whose name in the current directory was \lit{foo-bar}, but would not match the object whose multiple-component name in the current directory was \verb"foo/bar". One may also wildcard a name by giving a full regular expression. To do this, the regular expression should be enclosed within parentheses. For instance, specifying (Anne.*) is equivalent to specifying the wildcarded name 'Anne*'. In addition to any wildcards specified, a literal match for the wildcard will also happen. \subsection{Options} \meta{options} contains a (possibly empty) list of options to the \lit{LIST} command. If no options are specified, an empty list of options should be sent as a null token (\lit{'{}'}.) \subsubsection{Miscellaneous Options} Among the options supported are \lit{EXPAND} which tells the remote directory server to expand any union entries in the directory. By default, the response will contain the names of union links to be included, and the client must submit a new query. A directory server can ignore the \lit{EXPAND} option to the list command if it so desires. The \lit{LEXPAND} option is the same as \lit{EXPAND}, but indicates that the server should only expand union entries for local directories. The \lit{LEXPAND} option is implied if a multiple component name is being resolved. The \lit{VERIFY} option tells the remote server that the purpose of the query is to verify whether the remote directory exists and is a directory. No components are to be returned; instead, the message returned on success is \lit{NONE-FOUND}. \subsubsection{\protect\lit{ATTRIBUTES} option} The \lit{ATTRIBUTES} option indicates that the attributes associated with the link are to be returned. (If the object is on the same host as the directory, then the server may ignore CACHED attributes and return OBJECT attributes instead. \lit{ATTRIBUTES} is optionally immediately followed by an argument list, which is a parenthesized \mbox{\lit{+}-se}para\-ted list of attributes to be returned. If the \lit{ATTRIBUTES} option is specified without any attributes requested, then it is just the same as if one had specified \lit{ATTRIBUTES(\#INTERESTING)}. Note that union links do not normally have any interesting attributes attached to them, except for \lit{FILTER}. \lit{ATTRIBUTES(ID+FILTER)} is always implied. For \lit{EXTERNAL} links, \lit{ATTRIBUTES(ACCESS-METHOD)} is always implied.\footnote{ This restriction seems odd, but it makes certain details of programming the client libraries much easier.} There are some special arguments to the \lit{ATTRIBUTES} option. It is not a good idea for application-defined attributes to have names that conflict with these special arguments; if there are such application-defined attributes, you may have to use the \lit{\#ALL} special argument to look at their values. More than one special argument may be specified, and one may mix special and non-special arguments. Also, note that it is never erroneous for a server to return more attributes than were asked for, nor is it erroneous for a server to return attribute information even if no \lit{ATTRIBUTES} option was specified to the \lit{LIST} command. A server that always behaved as if the \lit{ATTRIBUTES(\#ALL)} option were specified would be behaving legally, although it would not be terribly efficient. \begin{description} \item[\lit{\#INTERESTING}] Return only interesting attributes. What constitutes an ``interesting'' attribute is server-dependent. This allows one to use Prospero for special applications. \item[\lit{\#ALL}] If this argument is specified, and the object resides on the same host as the link, then the attributes stored with the object referenced by the link will be returned in addition to those stored with the link, and no cached attributes will be returned (they would be irrelevant). If the object resides on a host different from the link, then all attributes stored with the link are returned, but not those stored with the object referenced by the link. \item[\lit{\#CACHED}] Return all attributes of type \lit{CACHED}. If you specify \lit{\#CACHED} with \lit{\#ALL}, the server will return cached attributes in addition to those that would be returned if you'd just specified \lit{\#ALL}. It is not clear how useful this behavior is. \item[\lit{\#OBJECT}] Return all attributes of type \lit{OBJECT}. Note that this will not work if the object does not reside on the same host as the link. \item[\lit{\#ADDITIONAL}] Return all \lit{ADDITIONAL} attributes \item[\lit{\#REPLACEMENT}] Return all \lit{REPLACEMENT} attributes. \item[\lit{\#LINK}] Return all \lit{LINK} attributes. \item[\lit{\#FIELD}] Return all fields (all system-defined standard attributes), except for ones that have already been returned as part of the \lit{LINK} response, such as \atr{host}, \atr{handle}, and \atr{dest-exp}. \item[\lit{\#\#FIELD}] Return all fields. (This option will be rarely used.) \item[\lit{\#APPLICATION}] Return all application-defined attributes. \end{description} \subsubsection{\protect\lit{FILTER} option} If the \lit{FILTER} option is specified, the \lit{LIST} command will be followed by one or more lines representing one or more \lit{PREDEFINED} filters to be applied at the server. The filters are applied in the order in which they follow the \lit{LIST} command. Their format is just like that of \lit{FILTER} information returned from the \lit{LIST} command (see subsection~\ref{filter}), except that the \meta{execution-location} field must always be \lit{SERVER}, and the first four tokens (``\lit{ATTRIBUTE LINK FIELD FILTER}'') are omitted. The format is: \begin{command} \lit{FILTER} \meta{filter-type} \lit{SERVER} \meta{pre-or-post} \lit{PREDEFINED} \meta{filter-name} \\ \zoos \lit{ARGS} \zoms\meta{filter-arg}\zome \zooe \end{command} The server will know that there are no more filter-specifying lines either when the end of the message is reached or it encounters a line that does not begin with the token \lit{FILTER}. \subsection{Returned Information} On failure, a standard error response will be returned. On success, the response will be a sequence of entries containing information about the requested files. \subsubsection{Links} \begin{command} \lit{LINK} \meta{link-type} \meta{target} \meta{name-component} \meta{host-type} \meta{host-name} \meta{hsoname-type} \meta{hsoname} \meta{object-version} [ \lit{DEST-EXP} \meta{dest-expiration} ] \end{command} In the case of links to objects, \meta{dest-expiration} is the value of the object's \atr{dest-exp} field. The \meta{link-type} token is defined as follows: \begin{description} \item[\lit{L}] Normal link (Symbolic link, link to a Prospero object, or link to an external object) \item[\lit{U}] Union link to a directory \end{description} The \meta{target} token is defined as follows: \label{target-token}(Also see the discussion of this in section~\ref{target-attribute}. A link may be a link to an object. In this case, the value of the \meta{target} token will be the same as the value of the object's \atr{base-type} attribute\footnote{For an explanation, see section~\ref{base type}.} (that is, \lit{OBJECT}, \lit{FILE}, \lit{DIRECTORY}, or \lit{DIRECTORY+FILE}.) Other values for \meta{target} are: \begin{description} \item[\lit{SYMBOLIC}] Symbolic link. The \meta{host-type} token will be \lit{VIRTUAL-SYSTEM}, the \meta{host-name} token will be the name of the virtual system being linked to (specified as a path within the current virtual system --- we usually use the conventional ugly-name of the virtual system), the \meta{hsoname-type} will be \lit{ASCII}, and the \meta{hsoname} will be the full pathname of the object being linked to within the virtual system. \item[\lit{EXTERNAL}] This is a link to an object which is not stored on a host running Prospero. Unlike other types of links, \lit{EXTERNAL} links have an \atr{access-method}% \footnote{See section~\ref{access-method} for a description of the \atr{access-method} field.} attribute which is returned as a cached attribute. This is because \lit{EXTERNAL} links cannot have any object attributes. Therefore, if one wishes to add attributes to an \lit{EXTERNAL} link that would normally be object attributes, one must specify them as \lit{CACHED}, \lit{ADDITIONAL}, or \lit{REPLACEMENT} attributes. \end{description} If the principal requesting the listing has no read access to a link, all fields in the link except for \meta{name-component} will be returned with the token \lit{NULL}, which is not otherwise valid in a returned link. \subsubsection{Link Attributes\label{Link Attributes}} If attributes were requested, the link will be followed by lines that specify the values of the requested attributes. The form of the response will depend on whether the attribute is associated with the link, or with the actual object. If the attribute is associated with the link, the \meta{applies-to} token indicates whether it applies to the \lit{LINK} or the object, and if the object whether it is a \lit{CACHED} attribute, a \lit{REPLACEMENT} attribute, or an \lit{ADDITIONAL} attribute. In case of conflicts between attributes associated with the link and those associated with the object, a cached attribute is superseded, a replacement attribute takes precedence, and an additional attributes leaves both intact. Attributes may sometimes be returned even if they were not explicitly requested. As a case of this, the \atr{ACCESS-METHOD} attribute is always returned for \lit{EXTERNAL} links. \begin{command} \ors \lit{ATTRIBUTE} \meta{applies-to} \lit{FIELD} \meta{attribute-name} \ooms\meta{value-tuple-element}\oome% \metaor \\ \lit{ATTRIBUTE} \meta{applies-to} \ors \lit{APPLICATION} \metaor \lit{INTRINSIC} \ore \meta{attribute-name} \meta{attribute-value-type} \ooms\meta{value-tuple-element}\oome \ore \end{command} \footnote{{\bf CHANGE IN FORMAT}: It used to be the case that the line returned for FIELD attributes did not include an \meta{attribute-type} token. This has been changed. The older format will continue to work until all Prospero applications before Alpha.5.1 are gone. Attributes may have multiple values, in which case one \lit{ATTRIBUTE} line is returned for each value. In the case of multiple values, the order in which attributes is returned may be significant to the application. The Prospero server will maintain the order of attributes. \meta{attribute-value-type}s are \lit{SEQUENCE}, \lit{LINK}, and \lit{FILTER}. \lit{SEQUENCE} is the most general \meta{attribute-value-type}. It is a sequence of zero or more ASCII strings, and all other attribute value types are subtypes of it. Since application attributes are, by definition, application-specific, we are not constraining the form of a sequence. However, if an application wishes to use application-specific subtypes of \lit{SEQUENCE}, we encourage application authors to use the first element of the attribute's value as a keyword describing the particular subtype of \lit{SEQUENCE}. One possible \meta{attribute-value-type} is \lit{LINK}. The \meta{value-tuple-element} tokens returned in this case are the same as the \lit{LINK} response to the \lit{LIST} command. In that case, the \meta{name-component} token will be ignored, and will usually be a zero-length string (\lit{'{}'}).) The return format would be: \begin{command} \lit{ATTRIBUTE} \meta{applies-to} \lit{APPLICATION} \meta{attribute-name} \lit{LINK} \ors \lit{L} \metaor \lit{U}\ore \meta{target} \meta{name-component} \meta{host-type} \meta{host-name} \meta{hsoname-type} \meta{hsoname} \meta{object-version} \zoos \lit{DEST-EXP} \meta{dest-expiration} \zooe \end{command} If the value of an attribute is a link, the link might itself have attributes. When such sub-attributes are returned, the word \lit{ATTRIBUTE} is immediately followed by \lit{>} signs to the appropriate nexting level. If a link attribute has sub-attributes, they will all be sent with the link. All available \lit{ID} fields will always be returned with every \lit{LIST} operation, using the \lit{ID} return format.\footnote{Please note again that ID fields have not been fully implemented, in the absence of an appropriate standard; comments about them in this document are subject to change.} \subsubsection{Filters\label{filter}} User-defined attributes and the field \atr{filter} may have the \meta{attribute-value-type} of \lit{FILTER}.\footnote{ XXX: This should go into the attribute documentation } If a link has one or more filters attached to it, they are specified as one or more instances of the link's \atr{filter} field. One \lit{ATTRIBUTE} line will always be returned for each filter. The lines are returned in the same order in which the filters will be applied to the link. The return format is: \begin{command} \lit{ATTRIBUTE}\zoms\lit{>}\zome \lit{LINK FIELD FILTER} \meta{filter-type} \meta{execution-location} \meta{pre-or-post} \\ \ors\lit{PREDEFINED} \meta{filter-name} \\ \metaor\ \lit{LINK} \lit{L} \meta{target} \meta{name-component} \meta{host-type} \meta{host-name} \meta{hsoname-type} \meta{hsoname} \meta{object-version} \zoos \lit{DEST-EXP} \meta{dest-expiration} \zooe \ore \zoms\lit{ID} \meta{id} \meta{info}\zome \\ \zoos \lit{ARGS} \zoms\meta{filter-arg}\zome \zooe \end{command} The values for \meta{filter-type} are: \lit{DIRECTORY}, filter is applied to the current directory; \lit{HIERARCHY}, filter is applied to all directories reachable through the filtered link; \lit{OBJECT} filter is applied to an object other than a directory; \lit{UPDATE}, filter is applied when updating the directory. \meta{execution-location} refers to where the filter will be executed. Filters are usually executed on the \lit{CLIENT}, but may be executed on the \lit{SERVER}. \meta{pre-or-post} is \lit{PRE} if the filter is to be applied before union links are expanded and \lit{POST} if the filter is to be applied after union links are expanded. \lit{POST} is the common case for client filters. Server filters must be \lit{PRE} at this time, since the server does not yet perform remote expansion of union links. Filters may be \lit{PREDEFINED}, which means that it is expected that the appropriate client or server will understand the predefined name, or they may be \lit{LOADABLE}, which means that they are object code that will be dynamically linked with the client or server.\footnote{ The security issues with loadable filters have not yet been fully addressed. Partly because of this, right now, all implementations except for the VAX implementation will only support \lit{PREDEFINED} filters, and even the VAX implementation is not configured to support loadable filters unless you specially compile it to do so. There may also be server-specific \lit{PREDEFINED} filters for special applications (such as Archie). Their \meta{execution-location} will always be \lit{SERVER}. One may specify zero or more arguments to the filter, following the \lit{ARGS} keyword. \subsubsection{Unresolved Components} An \lit{UNRESOLVED} response lists the components of the name that must be further resolved relative to the immediately preceding \lit{LINK} response or responses, and is used when not all components of a multiple-component name were resolved. \begin{command} \lit{UNRESOLVED} \meta{components} \end{command} The text of the \meta{components} must be a proper suffix of multiple-component name sent across as an argument to the \lit{LIST} command. For instance, to the command \begin{command} \lit{LIST '' COMPONENTS ulink-test2/murali/ROOT} \end{command} the only two legal \lit{UNRESOLVED} responses are \begin{command} \lit{UNRESOLVED} \lit{murali/ROOT} \lit{UNRESOLVED} \lit{ROOT} \end{command} \subsubsection{No files found} If no files are found, the reply will be: \begin{command} \lit{NONE-FOUND} \end{command} \section{LIST-ACL} \begin{command} \commandsize \lit{LIST-ACL} \meta{options} \zoos\meta{name-component}\zooe\selectlines \end{command} This request is used to list the access control list for the directory specified in the previous \lit{DIRECTORY} command, or for a link within the directory. The optional component is required only if requesting the \lit{ACL} for a link within the directory (option = \lit{LINK}). It is to be left out when requesting the \lit{ACL} for the directory itself (option = \lit{DIRECTORY}). The response will be zero or more lines of the form: \begin{command} \lit{ACL} \meta{entry-type} \zoos\meta{authentication-type} \zoos\meta{rights} \zoms\meta{principal-name}\zome\zooe\zooe \end{command} If no \lit{ACL} entries are listed, then the response is \lit{SUCCESS}. Fields inappropriate to a particular \meta{entry-type} need not be sent, but if they are sent, they should be sent as a zero-length string. For instance, the \lit{DEFAULT}, \lit{SYSTEM}, and \lit{DIRECTORY} ACL types do not use the \meta{authentication-type}, \meta{rights}, and \meta{principal-name} fields. If the ACL's permissions state that it cannot be viewed (\lit{v} or \lit{V} permission), then the response is \begin{command} \lit{FAILURE} \lit{NOT-AUTHORIZED} \zoos\text{optional multi-token explanatory text.}\zooe \end{command} Possible values for \meta{entry-type} include \lit{NONE} (allows access to no principals; in other words, it's a no-op), \lit{ANY} (grants access to all principals), \lit{OWNER} (grants access to the principal specified by the link or object's \atr{owner} field; i.e., the one who owns the link or object), \lit{NAMED}, %(formerly called \lit{LGROUP}), \lit{GROUP} (In this case, the \meta{authentication-type} token represents the group certification method), \lit{DIRECTORY}, \lit{DEFAULT}, \lit{SYSTEM}, \lit{AUTHENT} (means that an authentication method is used; the \meta{authentication-type} token specifies the authentication method. The only currently supported value for \meta{authentication-type} is \lit{KERBEROS}.), \lit{ASRTHOST}, and \lit{TRSTHOST}. An example: \begin{command} ACL ANY '{}' rlvY \\ ACL ASRTHOST '{}' ALRMDI prospero \\ ACL AUTHENT KERBEROS ALRMDI swa@ISI.EDU bcn@ISI.EDU \\ ACL DEFAULT '{}' '{}' \\ ACL SYSTEM '{}' '{}' \\ \end{command} We interpret a null link ACL as the \lit{DIRECTORY} ACL. We interpret a null directory ACL as the \lit{DEFAULT} ACL. See the Prospero User's Manual for a discussion of the order of evaluation of ACLs. If we want to find out the value of a \lit{NAMED} ACL (named ACLs are shorthand for longer lists, and are local to the server) (\lit{XXX} this should go into the user's manual), then we use the \lit{NAMED} option, and the \meta{name-component} is replaced with the (possibly quoted) name of the named ACL. Note that named ACLs are not currently supported. If we want to find out the value of an included ACL (Currently, the only included ACLs are \lit{SYSTEM}, \lit{DEFAULT}, and \lit{OVERRIDE}. \lit{DIRECTORY} is also an included ACL for the purposes of the protocol, but the value of the \lit{DIRECTORY} ACL will change from directory to directory, and therefore it is not a server-wide stable name.) \footnote{XXX: this information will go into the user's manual when we revise it}, then we use the \lit{INCLUDED} option, and the \meta{name-component} is replaced with the name of the included ACL. Note that retrieval of included ACLs is not currently supported. If we want the ACL for a filesystem object (instead of for a link or directory), then we use the \lit{OBJECT} option, and the \meta{name-component} is replaced with \meta{hsoname-type} \meta{hsoname} \zoos\meta{object-version}\zooe. Object ACLs are not currently implemented, because they wouldn't do anything useful --- we currently do not have an access method which understands Prospero ACLs. Within the Prospero protocol, the quoting mechanism works on principal names, and works recursively for distinguishing components of principal names. (This is currently only used by Kerberos, but may also be needed by other authentication mechanisms.) See the Prospero User's manual for a further discussion of ACLs. \section{GET-OBJECT-INFO} \begin{command} \commandsize \lit{GET-OBJECT-INFO} \meta{requested-attributes} \meta{hsoname-type} \meta{hsoname} \meta{object-version}\selectlines \end{command} This command requests information about an object. \meta{requested-attributes} is a list of those attributes that are desired. Multiple attributes may be separated by ``\lit{+}'' signs (with no intervening white space), just as options lists are separated. Special attribute names may be specified, just as they may be for the \lit{LIST} command. The special names are: \lit{\#OBJECT} (synonymous with \lit{\#ALL}), \lit{\#FIELD}, \lit{\#INTERESTING}, \lit{\#ALL}, and \lit{\#APPLICATION}. The response can be multiple lines, each containing a value for an attribute. The response will be the same as for the \lit{ATTRIBUTE} option to the \lit{LIST} command. However, the \meta{applies-to} field will always be \lit{OBJECT} An object that has migrated to another host may have its \atr{forwarding-pointer} attribute queried with \lit{GET-OBJECT-INFO}, but attempts to retrieve any other attributes will return a \lit{FORWARDED} message. If no matching attributes for the object were found, the response is \lit{NONE-FOUND}. \section{EDIT-OBJECT-INFO} \begin{command} \commandsize \lit{EDIT-OBJECT-INFO} \meta{modification-request} \meta{hsoname-type} \meta{hsoname} \end{command} This command is used to change the attributes of a Prospero object. It is followed by an arbitrary (zero or more) number of \lit{ATTRIBUTE} specification lines. See the \lit{LIST} command for a definition of these lines. The \meta{applies-to} will always be \lit{OBJECT}. In the command, one may request to add a new instance of an attribute, delete an instance, delete all instances, or replace all instances. The \meta{modification-request} will be \lit{ADD}, \lit{DELETE}, \lit{DELETE-ALL}, or \lit{REPLACE}. If you want to do more than one thing to an object in the same request (e.g., if you want to add one attribute instance and replace another), and you want to avoid letting the object exist in an intermediate and possibly inconsistent state, then you can send two \lit{EDIT-OBJECT-INFO} commands in the same message, along with the \lit{ATOMIC} command. If you are deleting all instances of an attribute, then the \meta{attribute-value} you specify in your \lit{ATTRIBUTE} specification lines will be ignored, and will usually just be the null string. \lit{DELETE-ALL} just checks for matches on the attribute name and the attribute namespace (\lit{APPLICATION}, \lit{FIELD}, or \lit{INTRINSIC}). \lit{DELETE}, on the other hand, checks for an exact match on the attribute name, namespace, type, and value. (The current implementation does not check for sub-attributes of a value of type link. \lit{REPLACE} may be specified even if the attribute does not yet have any instances specified for it. One may use \lit{EDIT-OBJECT-INFO} to edit the \atr{base-type} attribute to remove the \lit{FILE} type from it only if the file is empty (zero length), and one may remove the \lit{DIRECTORY} type from it only if the directory is empty (contains no links). \section{CREATE-LINK} \begin{command} \commandsize \lit{CREATE-LINK} \meta{options} \ors \lit{L} \metaor \lit{U} \ore \meta{name-component} \meta{target} \meta{host-type} \meta{host-name} \meta{hsoname-type} \meta{hsoname} \meta{object-version} \zoos\lit{ID} \meta{id-type} \meta{id-value}\zooe \end{command} This command creates a new link in the current directory. The \meta{name-component} may not be null, even if the link is a union link. If filters or other information must be added, the \lit{EDIT-LINK-INFO} command should be used once the link has been created. The \meta{options} may include \lit{REPLICA} to add a link to a directory that already contains a link with the same \meta{name-component}. \lit{REPLICA} indicates that the new link and the existing link or links with which it conflicts are replicas. Normally, if one attempts to add a link with a conflicting \meta{name-component}, the response is: \begin{command} \lit{FAILURE ALREADY-EXISTS} \end{command} if the new link duplicates an existing link (if all of the arguments to it are the same as those of an existing link), and \begin{command} \lit{FAILURE NAME-CONFLICT} \end{command} if the new link has information which conflicts with an existing link. If \lit{CONFLICT} is among the options, then conflicting links will be inserted into the directory anyway. For directories whose \atr{directory-ordering} is \lit{UNSORTED}, one of these three additional options may be specified: \begin{description} \item[\lit{BEFORE}] The \lit{CREATE-LINK} command is immediately followed by a \lit{LINK} line, describing the link before which the new link is to be inserted in the directory listing. \item[\lit{AFTER}] Same as above, but the new link is inserted after the specified link rather than before it. \item[\lit{LAST}] This is the default. The new link will be the last item in the directory. \end{description} \section{DELETE-LINK} \begin{command} \commandsize \lit{DELETE-LINK} \meta{options} \meta{name-component} \selectlines \end{command} This command is used to remove an entry from a directory. The options are currently blank. If the \lit{SELECT} lines are not specified and there are multiple links with the same \meta{name-component}, the first one matching will be deleted. \section{EDIT-LINK-INFO} \begin{command} \commandsize \lit{EDIT-LINK-INFO} \meta{modification-request} \meta{name-component} \zoos\lit{ID} \meta{id-type} \meta{id-value}\zooe \end{command} \begin{sloppypar} This command modifies information associated with a link. The interpretation of the %\ \linebreak[3] \meta{modification-request} and of subsequent lines is exactly the same as in the \lit{EDIT-OBJECT-INFO} command. \end{sloppypar} %\vspace{-.1in} \section{EDIT-ACL} \begin{command} \commandsize \lit{EDIT-ACL} \ors \lit{LINK+}\meta{options} \meta{name-component} \\ \hspace{.6in} \metaor \lit{OBJECT+}\meta{options} \meta{hsoname-type} \meta{hsoname} \\ \hspace{.6in} \metaor \lit{DIRECTORY+}\meta{options} \ore \\ \zoos\lit{ID} \meta{id-type} \meta{id-value}\zooe \meta{LF} \\ \lit{ACL} \meta{entry-type} \meta{authentication-type} \meta{rights} \meta{principal} \end{command} This command is used to modify an access control list for a directory, for a link within a directory, or for an object. If modifying the ACL for a directory or for a link within a directory, the directory is specified in the previous \lit{DIRECTORY} command. Another option indicates the operations to be performed (one of \lit{ADD}, \lit{SUBTRACT}, \lit{INSERT}, \lit{DELETE}, \lit{SET} or \lit{DEFAULT}), and whether to override the automatic inclusion of the system ACL (\lit{NOSYSTEM}), or limited administer access for the client (\lit{NOSELF}). The server will return \lit{SUCCESS}, \lit{FAILURE}, or \lit{FORWARDED}, as appropriate. \section{CREATE-OBJECT} \begin{command} \commandsize \ors\lit{CREATE-OBJECT} \lit{PHYSICAL+}\meta{options} \zoos\meta{hsoname-type} \meta{hsoname}\zooe \\ \metaor \lit{CREATE-OBJECT} \lit{ADD+}\meta{options} \zoos\meta{hsoname-type} \meta{hsoname}\zooe \\ \metaor \lit{CREATE-OBJECT} \lit{VIRTUAL+}\meta{options} \meta{name-component}\ore \meta{LF} \\ \zoms\lit{ATTRIBUTE} \meta{attribute-specifying-tokens}\meta{LF}\zome \\ \zoms\lit{ACL} \meta{ACL-specifying-tokens}\meta{LF}\zome \end{command} This command will create an object with the specified \meta{name-component} and will return the identifier that can be used to open it. The \meta{options} may include any or all of \lit{DIRECTORY}, \lit{FILE}, and \lit{OBJECT}. If the \lit{FILE} option is specified, the new file is created empty. If the \lit{DIRECTORY} option is specified, the new directory is created empty (i.e., not containing any links.). The object will be created with whatever attributes present that are specified in the \lit{ATTRIBUTE} lines. If \meta{options} includes \lit{VIRTUAL}, then \meta{name-component} is a name relative to the current directory, and a link to the new object is added to the current directory. If the \lit{ADD} option is specified, then one is adding a base type to an already created object. Exactly one of the \lit{ADD}, \lit{VIRTUAL}, and \lit{PHYSICAL} options must be specified. \begin{sloppypar} If the \lit{PHYSICAL} option and a \meta{hsoname-type} \meta{hsoname} pair are specified, then the server will attempt to create an object with that \meta{hsoname-type} \meta{handle-pair}. If the \lit{PHYSICAL} option without a following pair is specified then the server will choose a free \meta{hsoname-type} \meta{hsoname} pair. \end{sloppypar} Upon success, the server will return: \begin{command} \lit{CREATED} \meta{hsoname-type} \meta{hsoname} \end{command} It is up to the application to create a link to the new object. \subsection{Specifying Attributes} The new object's fields will be set to system defaults, but specifying a following series of \lit{ATTRIBUTE} descriptions allows the creator of a file to override those defaults, and to specify any application-defined attributes. The form for each \lit{ATTRIBUTE} line is the same as that returned by the \lit{LIST} command. \subsection{ACLs} If creating an object with the \lit{VIRTUAL} option, the access control list for the new object will initially be a copy of the access control list for its containing directory. If creating an object with the \lit{PHYSICAL} option, the access control list for the new object will contain the \lit{DEFAULT} ACL and the \lit{SYSTEM} ACL. In addition, for both options, one or more entries will be automatically added to the ACL granting its creator all rights. The entry authentication type or types will be appropriate for whatever the user used to authenticate himself or herself. (Either \lit{AUTHENT} \lit{KERBEROS} or \lit{ASRTHOST} or \lit{TRSTHOST}.) If the \lit{LPRIV} option is specified for a directory, instead of this entry, only those rights needed to allow the creator to set up the directory (list, read, insert, and administer) will be added, and (if \lit{VIRTUAL} was specified), only if the creator does not already have such rights through the ACL that was included from the parent directory.\footnote{If you really want to shoot yourself in the foot, you can then call \lit{EDIT-ACL} to remove these few rights. We will let you do this, but we are not making it easy for you.} If \lit{VIRTUAL} was specified, the ACL for the new link will by default be empty, which means that the default rights for the directory will apply to the link. After the ACL entries mentioned above are installed, the ACL entries specified as part of the \lit{CREATE-OBJECT} command will be added to the front of the list. \subsection{Some Error Conditions} If the user attempted to set a field whose name the server does not recognize, or to set a application-defined attribute to a type that the server does not recognize, or to set the value of any attribute with a string that the server cannot convert into the data type the server expects (e.g., too few tokens when setting an attribute of type \lit{LINK}), or to set an unrecognized ACL type, the response is: \begin{command} \lit{ERROR} \text{explanatory text} \end{command} If the user specified an explicit \meta{hsoname-type} and \meta{hsoname} with the \lit{PHYSICAL} option, but they were already in use, or if the user specified a component with \lit{VIRTUAL}, but the component is already in use, the error message is: \begin{command} \lit{FAILURE} \lit{NAME-CONFLICT} \zoos\text{explanatory text}\zooe \end{command} \subsection{No \protect\lit{DELETE-OBJECT} command} Although there is a \lit{DELETE-LINK} command, there is {\em no \/} \lit{DELETE-OBJECT} command. That's because Prospero objects will have their storage reclaimed when their TTL expires (when no link to them is refreshed before their expiration date). At the moment, this storage reclamation feature is not implemented.) \footnote{XXX: This feature must be specified. In addition, we must specify methods for refreshing links, garbage collection, and notification of the impending demise of objects.} \section{UPDATE} \begin{command} \commandsize \lit{UPDATE} \meta{options} \lit{COMPONENTS} \zoms\meta{name-component}\zome \end{command} This command tells the server to check each of the named components in the current directory for forwarding pointers. If the referenced object has moved, the link will be updated. The server will send Prospero protocol messages across the network to the targets of links to Prospero objects in order to check whether the target of a link has moved. (External links and symbolic links will not be checked.) If no components were specified, all components in the directory will be checked. Each \meta{name-component} may contain wild cards. On success, the \lit{UPDATE} command returns the number of links that were modified. \begin{command} \lit{UPDATED} \meta{number} \lit{LINKS} \end{command} On failure, the \lit{UPDATE} command returns the number of links it was unable to update.\footnote{ This error message may change in response to future needs.} \begin{command} \lit{FAILED TO UPDATE} \meta{number} \lit{LINKS} \end{command} Wildcards \section{STATUS} This command requests the current status of the server. A humanly readable multiple line response is returned. The response may be presented to the user without additional processing. The response must conform to the following requirements so that it may be read by a program if desired. The first line must include the server's software version identification enclosed in parenthesis, and the host name of the server. The name of the host should be the name that appears on local links generated by the server; it might not be the primary name of the host. The version identifier must be the first string that appears in parenthesis, and the host name must be the string that immediately follows the version identifier. If a line contains a colon (:), the string preceding the colon identifies the meaning of the text that follows the colon. Reserved identifiers include \lit{Contact}, \lit{Started}, \lit{Memory}, \lit{Data}, \lit{Root}, \lit{AFTP}, \lit{AFS}, and \lit{DB}. The identifiers are case insensitive. If present, \lit{AFTP} identifies the part of the file system accessible by anonymous \lit{FTP}. More than one \lit{DB} line may be present. A \lit{DB} line may contain more than one item on it; if it does, the items must be separated by spaces. Each item on a \lit{DB} line is an initial prefix which this particular server recognizes to mean that, if this server receives a system-level name with this prefix followed by a slash, the remaining contents of the line are fed to a database program which translates it into a reference to a virtual directory. Other than for the first line of the response, implementations are free to add or modify lines that do not contain a colons. A sample status response follows: \begin{verbatim} Prospero server (Beta.4.2B) JUNE.CS.WASHINGTON.EDU Requests since startup 4096 (3609+377+2 67+29+0 9 0+0+0 0 3) OF Started: 26-Aug-91 15:14:56 UTC Contact: bcn@cs.washington.edu Memory: 0(118)vl 0(4)at 0(5)acl 0(1)fi 1(1)pr 2(2)pt 0(711)str Data: /u1/vfs/pfsdat Root: / DB: ARCHIE GOPHER(70) GOPHERGW WAIS AFTP: /homes/june/ftp \end{verbatim} Since the responses to this command are so free in form, it is unlikely you would want to send additional requests to the Prospero server along with the \lit{STATUS} request, since it would not be easy for a program to separate the replies to them from the free-form text. \chapter{Standard Responses} \section{SUCCESS} \begin{command} \commandsize \protect\lit{SUCCESS} \zoos\protect\text{identifying-info}\zooe \end{command} A command that does not generate any output returns this response if successful. \section{FORWARDED} \begin{command} \commandsize \protect\lit{FORWARDED} \protect\meta{host-type} \protect\meta{host-name} \protect\meta{hsoname-type} \protect\meta{hsoname} \protect\meta{version} [ \lit{DEST-EXP} \meta{dest-expiration} ] \\ \protect\zoms \protect\lit{ID} \protect\meta{id-type} \protect\meta{id-value}\protect\zome \end{command} This response is returned when the object that is the target of an operation has moved. The client can retry the response using the corrected information. \section{ERROR} \begin{command} \commandsize \protect\lit{ERROR} \protect\text{text} \end{command} This response is returned to indicate an error encountered when parsing the request. The error might be a protocol error, or it might be the result of the server's inability to recognize a keyword or data type. \text{text} describes the error. \section{FAILURE} \begin{command} \commandsize \protect\lit{FAILURE} \protect\meta{identifying-info} \zoos\protect\text{optional text} \zooe \end{command} This response is returned when an operation can not be performed. The defined values for \meta{identifying-info} appear below. If present, the \text{optional text} provides additional information about the failure. \begin{command} \lit{NOT-FOUND} \ors\lit{FILE} \metaor \lit{ACL} \metaor \lit{OBJECT} \metaor \lit{FILTER} \metaor \lit{PARAMETER} \metaor \lit{ATTRIBUTE} \ore \\ \lit{ALREADY-EXISTS} \\ \lit{NAME-CONFLICT} \\ \lit{AUTHENTICATION-REQUIRED} \\ \lit{NOT-A-DIRECTORY} \\ \lit{NOT-AUTHORIZED} \\ \lit{AUTHENTICATION-DATA} \\ \lit{SERVER-FAILED}\footnote{This is used in the following situations, among others: if an internal table in the server fills up, or if the server cannot allocate enough memory to handle the request, or if the server detects an internal inconsistency in its database, or if the server has not implemented a command specified in the protocol.}\\ \lit{AMBIGUOUS} \\ \lit{BAD-VALUE} \\ \lit{FILTER-APPLICATION} \\ \end{command} \section{WARNING} \begin{command} \commandsize \protect\lit{WARNING} \protect\meta{identifying-info} \zoos\protect\text{optional text}\zooe \end{command} This response is returned to indicate a warning condition which does not affect the correctness of the response. This message can be used to indicate that the client is using an old version of the protocol that, while supported, should be phased out. It can also be used to inform the client of future changes on the server or scheduled downtime. The defined values for \meta{identifying-info} appear below. \text{optional text} is optional text that provides additional information about the warning. \begin{command} \lit{OUT-OF-DATE} \\ \lit{MESSAGE} \\ {\em Any \meta{identifying-info} that can follow a \lit{FAILURE} message} \end{command} Prospero clients are strongly encouraged to present warnings to the user. \appendix \chapter{Directory, Link, and Object Attributes\label{db}} This appendix describes the object and directory information maintained by the Prospero file system. {\bf \large Please note that this appendix is in very rough form. Many of the attribute definitions have not yet been properly written. A lot of the attribute documentation can be found in section~\ref{Link Attributes} of this document.} Attributes have three namespaces associated with them: \lit{APPLICATION} attributes, \lit{INTRINSIC} attributes, and \lit{FIELD}s. Attributes in the \lit{FIELD} namespace have a registered meaning, and are understood by all clients and servers that use them. \lit{APPICATION} attributes are defined by users and application programs and are unrestricted. Intrinsic attributes have special registered meanings, providing prossibly transient or derived information. The server has flexibility about whether it allows you to change these things. Modifying them may have special implications --- for instance, setting the \atr{SIZE} of a file to ``\lit{0 bytes}'' will truncate the file. \lit{INTRINSIC} attributes gare either not modifiable, or else the server uses special mechanisms to modify them. In addition, there is a fourth namespace used internally by routines running on the Prospero server. \lit{INTERNAL} attributes are never sent across the network; they cannot be read with GET-OBJECT-INFO or LIST and cannot be modified with EDIT-OBJECT-INFO. However, they do appear in the server's data files. \section{Objects} \subsection{Attributes\label{access-method}} Valid attributes include {\sc access-method, closure, description, forwarding-pointer, keywords, last-referenced, last-writer, locks, owner, replicas, size, storage-location, ttl, ttl-expires. version-number, virt-sys, well-known-names,} and {\sc write-date}. Prospero maintains the following system defined attributes for each Prospero object: \begin{description} \item[\atr{base-type}] See section~\ref{base type} for a description of this attribute. \footnotetext{ {\bf RATIONALE}: Under the version 1 protocol, the means of obtaining the access method information for \lit{EXTERNAL} and \lit{FILE} links was different; this made the code more complicated than it needed to be. The reader may well ask why the host should be specified in the value of the \atr{access-method} field. Isn't the host name already specified in the \atr{host} field? Including the host name as part of the attribute's value has some advantages: \begin{itemize} \item The value of the \atr{access-method} field is all one needs in order to retrieve the file. \item One might have a Prospero server running on only one host in a cluster, where the objects themselves are actually stored on another fileserver. Then, one would want to be able to have the \atr{access-method} host be different from the host which is listed as the one having the final word on the status of the object. \item This system also allows us to have a gateway server, which is able to translate directory formats from other distributed file systems (e.g., gopher), but directs the client to retrieve the files themselves from a host that is not the gateway server. \end{itemize} \item[\atr{access-method}\footnotemark] This is a tuple of at least 5 elements. The first element is the name of the access method. Currently supported values are \lit{AFTP}, \lit{GOPHER}, \lit{AFS}, \lit{NFS}, \lit{FTP}, \lit{WAIS}, and \lit{LOCAL}. The next 2 elements are the \meta{host-type} and \meta{host-name} of the host to which the access method should connect in order to retrieve the object. A port number may be included as part of the hostname, if relevant. If they are zero-length tokens (\lit{'{}'}), then they default to the \meta{host-type} and \meta{host-name} specified in the link. The next 2 elements are the \meta{hsoname-type} and \meta{hsoname} which the access method will use to retrieve the object. If they are zero-length tokens, then they default to the \meta{hsoname-type} and \meta{hsoname} specified in the link. This constraint on format applies to all access methods. If a particular type of access method doesn't need one of these fields, then it still must be specified, but the access method is free to ignore it. The whole point of the \lit{'{}'} shorthand is merely to save bytes in the protocol messages. It is always appropriate to send them fully expanded, and not use the \lit{'{}'} shorthand. The sixth and subsequent elements are dependent upon the particular access method. For \lit{AFTP} and \lit{FTP}, the sixth element will be \lit{BINARY} or \lit{TEXT}. For \lit{NFS}, the sixth element will be the name of the filesystem on the remote host. \lit{LOCAL}, and \lit{AFS} have only five-element names. The \lit{GOPHER} access method may have five or six elements in the name. The actual protocol used to retrieve a document or object through Gopher varies depending on its Gopher item-type. (See Internet RFC 1436 for details on the interpretation of the Gopher item-type characters.). This item type is usually the 1st character of a Gopher document or object's selector string (the \meta{hsoname} element of the access method). However, the protocol does not require that this be the case. If a sixth token is present in a \lit{GOPHER} access method, it will be treated as the Gopher item-type character; otherwise, the item-type will be taken from the 1st character of the \meta{hsoname} element. Some examples: \begin{command} \tt \sloppy ATTRIBUTE FIELD ACCESS-METHOD GOPHER %\linebreak[2] INTERNET-D~MERMAID.MICRO.UMN.EDU(150) ASCII~\mbox{'1/Fun Stuff/Pyrotechnics/PyroGuide\ 1'}% \footnote{This file recently disappeared from the server. If you have a copy, please send it to \verb"swa@isi.edu".} {\rm \par This access method could also be displayed in the six-token format as:} \tt \sloppy ATTRIBUTE FIELD ACCESS-METHOD GOPHER %\linebreak[2] INTERNET-D~MERMAID.MICRO.UMN.EDU(150) ASCII~\mbox{'1/Fun Stuff/Pyrotechnics/PyroGuide\ 1'}~1% \footnote{This file recently disappeared from the server. If you have a copy, please send it to \verb"swa@isi.edu".} {\rm \par Andrew File System names are the same irrespective of what host one is using them from. Therefore, the \meta{host-name} token in the access method is irrelevant and is ignored by the client.} ATTRIBUTE FIELD ACCESS-METHOD AFS DUMMY DUMMY ASCII~\mbox{/grand.central.org/doc/afs/dce/usenix90/README} {\rm \par This file can be retrieved by NFS mounting the {\tt /auto/gum/gum} filesystem on the host PROSPERO.ISI.EDU. Note that the server is responsible for knowing which client machines it will allow to NFS mount that filesystem.} ATTRIBUTE FIELD ACCESS-METHOD NFS INTERNET-D~PROSPERO.ISI.EDU ASCII~\mbox{ftp/pub/prospero/README-prospero-documents} \mbox{/auto/gum/gum} {\rm \par \meta{hsoname} tokens in the \lit{FTP} access method are full local hostname paths that one would give when using full FTP to the host.} ATTRIBUTE FIELD ACCESS-METHOD FTP INTERNET-D~PROSPERO.ISI.EDU ASCII~\mbox{/ftp/pub/prospero/README-prospero-documents} TEXT {\rm \par \meta{hsoname} tokens in the \lit{AFTP} access method are pathnames relative to the root of the anonymous FTP area.} ATTRIBUTE FIELD ACCESS-METHOD AFTP INTERNET-D~PROSPERO.ISI.EDU ASCII~\mbox{/pub/prospero/README-prospero-documents} TEXT {\rm If one is querying from a host which has a file accessible via the local filesystem, and if the server has knowledge of this fact, a \lit{LOCAL} access method will also be returned for a file. For the \lit{LOCAL} access method, the \meta{host-name} token in the access method is ignored.} ATTRIBUTE FIELD ACCESS-METHOD LOCAL '' '' ASCII~\mbox{/auto/gum/gum/ftp/pub/prospero/README-prospero-documents} \end{command} \item[\atr{closure}] The \meta{attribute-type} of thie attribute is \lit{LINK}. It is a link to the virtual system to be used when resolving names embedded in the object. The link's \meta{name-component} will be ignored, but by convention it is the ugly-name of the virtual system. \item[\atr{owning-virtual-system}] The \meta{attribute-type} of this attribute is \lit{LINK}. It is a link to the description of the virtual system which is considered to own the object. (Every virtual system, by convention, has a link to its description named \lit{/VS-DESCRIPTION}. For directories, if you are logged into the directory's \atr{owning-virtual-system}, then if you try to change the directory, your client will assume that you really want to try to change the directory. If you are logged into a different virtual system from the directory's \atr{owning-virtual-system}, then if you try to change the directory, your client will assume that you really want to customize your own virtual system, but not affect the master directory. Your intentions are completely distinct from whether you actually have write permission on the directory. If you try to change a directory that you can't write to (if its \atr{owning-virtual-system} is the same as the virtual system you're logged into, but you don't have permission to write to it), then the current clients will all give you a ``permission denied'' error message, and the nice ones will suggest that you might want to change virtual systems and customize instead. The link's \meta{name-component} will be ignored, but by convention it is the ugly-name of the virtual system. \item[\atr{version-number}] The \meta{attribute-type} of this attribute is \lit{SEQUENCE}. It is represented in the protocol as a decimal number. It is currently always zero; see section~\ref{object version numbers} for further details. \item[\atr{owner}] The principal responsible for the object. The \meta{attribute-type} of this attribute is \lit{SEQUENCE}. It is a tuple of three or more elements. The first element is an ACL \meta{entry-type} and the second element is an ACL \meta{authentication-type}. The third and subsequent elements are \meta{principal-name}s. The first two elements are needed because they indicate the namespace in which the \meta{principal-name}s are to be resolved. There may be multiple instances of the \atr{owner} field, if the owner wants to be registered according to several authentication systems. For instance, one of the authors of this document uses an \atr{owner} field that looks like this: \begin{command} \lit{ATTRIBUTE FIELD OWNER ASRTHOST '' swa@128.9.*.*} \\ \lit{ATTRIBUTE FIELD OWNER AUTHENT KERBEROS swa@ISI.EDU swa/padmin@ISI.EDU} \\ \end{command} Although the \atr{owner} field may be referred to with the \lit{OWNER} ACL type, we don't really encourage people to use it as a shorthand for granting access rights. Its primary purpose is informational. \item[\atr{forwarding-pointer}] This attribute has type \lit{LINK}. The link's \meta{target} is \lit{FP}. It is set for objects that have migrated to another host. The target of its value is the new location of the object. If an object has moved to a new host, its \atr{forwarding-pointer} will be returned in a \lit{FORWARD} protocol message in response to any attempts to access it. \item[Last writer, write date, etc.] \item[Version info] (optional). Number of versions to keep, version number, etc. \item[Attributes or keywords] (optional). User specified. \item[Short description] (optional). \item[Locks] (optional). \item[List of replicas] (optional). \item[Replication type] (optional). \item[Other replication information] (optional). \item[Time to live]. The lifetime for newly created or refreshed links to the object. \item[\atr{ttl-expires}] This is the \atr{ttl} plus the time that a link to the object was last created or refreshed. \item[Back links]. A possibly incomplete list of directories with links to the object. \end{description} Note that the object's name is not one of its attributes. The object's name is the concatenation of the name components starting from the active virtual system. An object may have different names in different virtual systems, or even multiple names within a single virtual system\footnote{Despite this, well known names from agreed upon starting points might be entered as application-defined attributes for objects.}. \subsection{Objects stored on \unix} Objects stored on \unix\ servers have the following attributes defined for them. These are all \lit{INTRINSIC}: \begin{description} \item[\atr{size}] A single-element \lit{SEQUENCE} specifying the number of bytes used to store the object. Its format is ``\meta{number} \lit{bytes}''. Note the embedded space. \item[\atr{native-owner}] A single-element \lit{SEQUENCE}. The \unix\ username on the server of the user who owns this file. \item[\atr{native-owner}] A single-element \lit{SEQUENCE}. The \unix\ group name on the server of the group associated with this file. \item[\atr{last-modified}] A single-element \lit{SEQUENCE}. The ASN-TIME representation of the last modified time of this object. \item[\atr{unix-modes}] A single element \lit{SEQUENCE} consisting of a ten character string. The first character is ``\lit{l}'' for symbolic links, and ``\lit{-}'' otherwise. The remaining 9 characters are the user, group, and other protection bits in the standard format returned by ``\lit{ls -l}''. \end{description} \subsection{Persistence} An object continues to exist until the last non-expired link referencing the object is removed. If a user wishes to recover the storage space for an object, it is flagged for removal. When links to the object are refreshed, notification is sent that the object is about to disappear, and anyone wanting to maintain their reference must copy the object elsewhere. Subsequent users have the option of making their own copy, or updating their link to refer to one of the new copies. \subsection{Mobility} Objects may move from one site to another. If they do, a forwarding pointer must remain at the old location until the time-to-live expires. This enables anyone with a non-expired link to the object to refresh the link and record the object's new location.\footnote{To place a forwarding pointer, set the old object's \atr{FORWARDING-POINTER} atribute. It must be manually moved to the new server at this time.} \section{Directories} A directory is an object and as such, everything that applies to objects also applies to directories. The physical representation of a directory is interpreted by the Prospero server on the system storing the directory. The Prospero protocol defines the interface through which a directory is accessed. \subsection{Directory Attributes} The following attributes are defined for directories: \begin{description} \item[\atr{directory-ordering} (not yet implemented)] This attribute is a 3-tuple. The default value is \begin{command} \lit{SORTED NAME-COMPONENT INCREASING} \end{command} which means that, by default, directory entries are sorted in increasing order according to the value of their \atr{name-component} attribute. The first element of the tuple is \lit{SORTED} or \lit{UNSORTED}. If \lit{UNSORTED}, the next two elements must be null. If \lit{SORTED}, the second field specifies an attribute which is the sort key. The third element is either \lit{INCREASING} or \lit{DECREASING}, meaning the order of sorting.% \footnote{In the current implmentation, the only sort keys that may be specified must have an \meta{attribute-type} of \lit{ASCII}.} If the \atr{include-native} attribute is set to any value other than \lit{NONATIVE}, then the \atr{directory-ordering} cannot be \lit{UNSORTED}. \item[\atr{include-native} (not yet implemented)] Whether to include information from the native filesystem in the directory. If files are included, they will be included from the real directory on the server with the same \meta{hsoname} as the Prospero directory. Its \meta{attribute-type} is a single-element \lit{SEQUENCE}. Values are: \begin{description} \item[\lit{NONATIVE}] Do not include files from native directory. \item[\lit{INCLNATIVE}] Include all files from native directory. \item[\lit{INCLREAL}] Smae as above, but (for the \unix\ server) do not include ``\lit{.}'' and ``\lit{..}''. \item[\lit{NATIVEONLY}] All entries in directory are from native dir; no links have been added. For the \unix\ server, ``\lit{.}'' and ``\lit{..}'' are NOT included. \item[\lit{PSEUDO}] Directory is not real. This is set for all directories returned from filters and by Archie and Gopher. \end{description} \end{description} \subsection{Link Attributes\label{target-attribute}} Prospero directories contain links to the objects that are included in the directory. The following information is maintained for each link. \begin{description} \item[\atr{name-component}] This is the single component of the object's path relative to the current directory. Its \meta{attribute-type} is \lit{SEQUENCE}. \item[Short description of link] (Optional). \item[\atr{link-type}]. The type of a link can be either normal [L] or union [U]. In the case of a normal link, an entry for the link is visible when the directory is listed. In the case of a union link, which can only be made to another directory, the links from the target directory appear as part of the directory from which the union link originates when the originating directory is listed. If multiple objects have the same name, the order in which the union links appear determines which object is visible. Two types of links which may appear locally (either in the server, or on the client) are [-] deleted, and [N] native. It is not legal for these codes to be sent across the network. Type [N] links are converted to [L] and type [-] are skipped entirely. \item[\atr{target}] Target of link: For links in a directory that don't point to objects, could be \lit{SYMBOLIC} or \lit{EXTERNAL}. For a forwarding pointer it is \lit{FP}. Links to objects will have a target field indicating the cached value of the object's \atr{BASE-TYPE} attribute. When stored on a vlink structure, it may have exactly one of the following forms: \lit{OBJECT}, \lit{FILE}, \lit{DIRECTORY}, \lit{DIRECTORY+FILE}. There is no guarantee that the type of the target has not changed. Thus, this field is the cached value of the object's base type. For union links, this field is always \lit{DIRECTORY} or \lit{DIRECTORY+FILE}. See section~\ref{target-token} for a further discussion of this. \item[Hidden/Not-Hidden/Externally-Hidden\footnote{Not yet implemented}] By default, a hidden link is not displayed when a directory is listed. It is, however, returned by the directory server, and is traversed if the actual name is specified in a pathname. An Externally-Hidden link is a hidden link that will be displayed if the current virtual system is the same as the owning virtual system for the directory containing the link. The user may override the hidden option, causing hidden links to be listed. Note that it is also possible to hide a link by specifying its protection as non-listable. Such links will {\bf only} be returned by the directory server when the actual name of the link has been specified. \item[\atr{filter}] Multiple filters allowed. The filter attribute is a pointer to a program that can be used to filter the contents of directories to which links are made. {\it data} is the set of optional arguments passed to the filter program. In addition to the linked directory and arguments, the filter has access to all other information available from the current directory. Filters come in several types. By default, a filter is a directory filter, and is applied when searching directories. A hierarchy filter is similar to a directory filter. The difference is that a directory filter is applied to a single directory, while a hierarchy filter is applied to the entire hierarchy (including subdirectories) reached through a link. Directory and hierarchy filters come in two types. The default is post-expansion. The filter is applied after all union links have been expanded. A pre-expansion filter is applied before union links are expanded. An object filter is applied when accessing an object other than a directory, and might be used, for example, to cause some operation to be performed on the object before it is accessed. Note, however, that all types of filters are associated with links. Filters are applied to a directory in the order of pre-or post expansion, decreasing depth of the links to which they are attached (for hierarchy filters), and finally in the order that the filters are specified on the traversed links. \item {\bf Attributes} (optional). Application attributes to be associated with the link. This allows a user or application to add (or override) attributes to the linked object (which might be owned by someone else, and thus not modifiable). \item[\atr{host}] The name of the host on which the object can be found. \item[\atr{host-type}] The type of the hostname. In particular, whether the hostname is an Internet address, a domain style name, or a name in some other naming system. Note that a symbolic link is a link where the destination host is a virtual system, and the destination object name is a name relative to that virtual system. \item[\atr{hsoname}] Host-specific object name. The name of the object relative to the destination system. \item[\atr{hsoname-type}] The type of \atr{hsoname}. Different types of names include numerical file IDs, names relative to the root of the local file system, etc. Right now, only pathnames are implemented, and their type is \lit{ASCII}. \item[\atr{object-version}] By specifying a version number in a directory link, the link is made to a specific version of the object, and changes to the object will not be visible through the link. \item {\bf Access control info} (optional). Allows restrictions on who can read or modify individual directory entries. These are really attributes, though they are in fact retrieved and modified with LIST-ACL and EDIT-ACL, and do not appear on the normal attribute listings. \item[\atr{dest-exp}] {\bf Destination expiration date and time}. Its implied type is a single-element {\tt SEQUENCE}, in ASN-TIME format.\footnote{ Implementers should use the {\tt asntotime()} function in the {\tt pfs} library in order to convert an ASN-TIME string into a \unix\ timestamp, and the {\tt timetoasn()} function to perform the reverse conversion. Applications writers are encouraged to use ASN-TIME format to represent all timestamps sent across the network. This entry indicates how long the information in the link should be considered valid. When an object is accessed through a link, the destination expiration date should be set to the current time plus the destination time-to-live. Note that expired directory entries do not disappear. Typically they remain valid. The expiration means that there is no longer a guarantee that the object originally referenced can still be found. \item {\bf ID}. When a new object is created, a unique object identifier may be assigned. This identifier can be included in links, and used to further verify that the named object is the one that is actually desired. It allows one to reference objects after their expiration dates with the guarantee that if these identifiers match, it is the same object. In the prototype, the object identifier is a random number of type REMOTE. Other types of object identifiers will be defined after more work is done by an IETF working group. \item {\bf Valid-till} (optional). If a link is a cached value, then this field indicates how long the entry should be considered valid. For example, a symbolic link may have a corresponding cached hard link. Until its expiration a cache entry may be used instead of searching based on the symbolic link. If this field is 0, then the link is not a cached entry. \item {\bf Last-update} (optional). This is the time the link was last updated. Its expected use is for resolving conflicting updates in replicated directories. \end{description} \subsection{Replication} When support for replication is added to Prospero, a directory might include multiple links with the same name for the same object. Not all replicas need be listed, however, because each replica will maintain its own list of siblings. Multiple entries are important to increase reliability and availability. \chapter{Asynchronous Reliable Delivery Protocol\label{ardp}} This appendix describes the asynchronous reliable delivery protocol (ARDP) used by Prospero. As used by Prospero, this protocol is layered on top of the Internet User Datagram Protocol. % \cite{udp}. Prospero implements its own ARDP because at the time of initial development we were unable to find any that were suitable for general use. Most systems that use any sort of reliably delivered message protocol implement their own around the specific needs of their application. Like these other systems, early versions of the Prospero protocol defined the mechanisms needed for retries and packet sequencing. As these mechanisms were refined, the functionality was moved to a separate protocol layer (and is implemented as a separate library) to improve modularity, and in hope that this general and simple ARDP can be used for other purposes. The ARDP protocol is designed for a request/response style of interaction, where a client sends a request message to a server in one fell swoop and receives a reply message from the server. The server can send the packets composing the reply message slowly, as data becomes available, while it is still processing the rest of a reply. In the current implementation, each request message sent by a machine from a particular port has its own connection id. ARDP was designed so that in the common case, the additional overhead of guaranteeing reliability is as small as possible. Unless special processing is required, the header is kept small, and unless a packet is lost, no additional packets are sent. If a field is not specified, the default value is used in its place. All fields up to and including the last field specified must be filled in, but the header may be truncated at any point, after which all remaining fields take on their default values. The ARDP header contains the following fields: \begin{description} \item[Octet 0] Version and header length: High order two bits are ARDP version number mod 4 (this is version 0). Low order six bits are the header length including octet 0.\footnote{The length of the total packet, including data, is available via the UDP layer, as are the port and IP address of the sending host.} \item[Octets 1--2] Connection ID: Defaults to zero. It must be specified in the response to any request that specified a non-zero connection ID. \item[Octets 3--4] Packet number: Defaults to 1 if not specified. A specified value of 0 indicates an unsequenced control packet which should not be passed to the application. Note that unsequenced control packets cannot request acknowledgements, nor is there any way for the sender of such a packet to be sure that they have arrived. \item[Octets 5--6] Total number of packets in this message: Defaults to 0 if not known, or retains current value if it was provided in any earlier messages. If the packet number was also not specified, then it defaults to 1. A specified value of 0 means use the default. \item[Octets 7--8] Received through: Sequence number through which all packets have been received by the sender of this packet. Defaults to current value if specified in previous message. Defaults to 0 otherwise. The recipient's count of packets received through is normally monotonically increasing; this keeps the count from being set backwards in case an out-of-order packet is received. However, if the ``reset received through'' option (option 2) is specified in octet 12, then it means reset to 0 (i.e. it forgot or lost the earlier messages). More generally, specifying any explicit value for this field along with the ``reset received through'' option resets the peer's count, possibly backwards. The recipient should not set its internal value of this field backwards unless the ``reset received through'' option is set. \item[Octets 9--10] Wait (expected time till response): Defaults to current value. Specified value of 0 means revert to client-specified backoff algorithm. Specifying a non-zero value lets the client know that a request might not be processed for some time and that the client should not retry the request until the specified time. The client may retry sooner if it believes messages are available which have been missed (e.g., gaps in the list of received packets). This is an unsigned quantity, measured in seconds, in network octet order (i.e., octet 9 is more significant than octet 10). A specified value of 65,535 (\(\mbox{FFFF}_{16}\); all bits turned on) means greater than or equal to 65,535 seconds until the next packet. (We do not expect that this value will ever be used, but it is defined for the sake of completeness.) \item[Octet 11] Flags: Octet 11 is a bit vector specifying option flags. The flags may themselves require additional fields specific to the flag. These fields appear at the end of the header in the order they are needed when reading flags from the low order bit to the high order bit, followed by any extra fields needed by the flag specified by the 12th octet. %% It does not appear to be possible to start a \lit{MINIPAGE} inside %% a \lit{TABULAR} environment. LaTeX is really awful about not permitting %% recursive application of its constructs. I wish there were %% something better out there. --swa %% & \begin{minipage} \end{description} %\begin{table}[h] \begin{center} \begin{tabular}{|l|p{3.5in}|p{2.0in}|} \multicolumn{3}{c}{Value of flags for octet 11} \\ \hline Bit No. & Meaning & Additional Fields \\ \hline 0 (low order) & Additional Address Information Follows & Variable length (see below)\\ \hline 1 & Priority Follows & 2 octets (see below)\\ \hline 2 & A Protocol ID for a higher-level protocol follows & 2 octets (see below) \\ \hline 3--5 & Unused & \\ \hline 6 & This packet is a sequenced control packet only; it should not be returned to the application by the ARDP library. & None \\ \hline 7 (high order) & Please Acknowledge this Packet & None \\ \hline \end{tabular} \end{center} %\end{table} \begin{description} \item[Octet 12] More Options: Octet 12 specifies exactly one (1) of up to 256 other options. The options may themselves require additional fields specific to the options. (See discussion at Octet 11). \end{description} %\begin{table}[h] \begin{center} \begin{tabular}{|l|p{3.0in}|p{3.0in}|} \multicolumn{3}{c}{Value of options for octet 12} \\ \hline Value & Meaning & Additional Fields \\ \hline 0 & No Option Specified & None \\ \hline 1 & Client to server: Cancel Request. Server to client: Connection refused. & None \\ \hline 2 & Reset peer's received-through count. & Specified in octets 7--8 \\ \hline 3 & Packets received beyond received-through & The rest of the header after additional data for octet 11 flags is an arbitrary number of octets. These are bit-vectors specifying which packets beyond the received-through specified in this packet have been received by the sender of this packet. For example, if the received-through is set to 43, then we know that packet 44 has not been received. The low order bit of the first octet of the additional field will be turned on if packet 45 has been received, and off if it has not. The high-order bit will be turned on if packet 52 has been received, and off if it has not. Similarly, the low-order bit of the second octet of additional information will be turned on if packet 53 h as been received, and so on. The recipient of this information may choose to ignore it and use a simpler resend strategy. Similarly, this information is never required to be sent. \\ \hline 4 & Redirect (used by servers): The client should send any unacknowledged packets already sent and all subsequent packets in this message to a new addresss. This is designed to be used as a load-shedding device. In one common case, this will be the entire response a server gives to a request, and the client will resend the entire request to a new server; in the other common case, this will be used in conjunction with option 6 or 7. & 6 octets. The first 4 octets are the IP address of the new server, in network byte order. The next 2 octets are the UDP port to which the request should be sent, also in network byte order. \\ \hline 5 & Redirect and notify (used by servers). Like option 4, but the client's network layer should also notify its caller that all subsequent requests intended for the old server should be sent to the new server instead. & Same as option 4. \\ \hline 6 & Forwarded: This request was received from a client, and the sender is a server forwarding it to the recipient for processing. The recipient should pretend that it received this message from the sender indicated by the additional fields, not from the real sender of this message. (If implemented, this request should be accepted only from one of a group of trusted hosts.) This option is intended to be used by a central server which distributes requests to several subsidiary servers which do the actual work of processing the request, but which use the central server as a contact point. Presumably, it is cheaper for the central server to forward the request to the subsidiary servers over a local area network rather than for the client (who may be quite far away) to retransmit it. The central server has done the job of notifying the original client (through option 4 or 5) that further requests and retransmissions should go to the new server. & 6 octets: The IP address and port of the original sender of this message, as in number 4. \\ \hline \end{tabular} \begin{tabular}{|l|p{3.0in}|p{3.0in}|} \multicolumn{3}{c}{Value of options for octet 12} \\ \hline 7 & Forwarded; Please notify: Like option 6, but the receiving server should notify the client of the switch (through option 4 or 5).% \footnotemark & 6 octets: The IP address and port of the original sender of this message, as in number 4. \\ \hline 8-252 & Undefined & Undefined \\ \hline 253 & Request Queue Status & 1 octet. If bit 0 (low order) is set, the position in the queue is requested. If bit 1 is set, the estimated time until this request will be completed is requested. The recipient may ignore this option. \\ \hline 254 & Response to 253. & 1 octet of flags, followed by 1 or 2 additional fields. If bit 0 (low order) of the flags is set, the position in the queue is returned as a 2 octet network byte order representation of an unsigned quantity. A value of \hexnum{FFFF} (all bits turned on) means a queue position of \hexnum{FFFF} or further. (We do not expect this value to ever be used, but it is included for the sake of completeness.) If bit 1 of the flags is set, the estimated time until this request will be completed is returned as a 4-octet network byte order unsigned value, representing a time in seconds. A value of \hexnum{FFFFFFFF} (all bits turned on) means a time of \hexnum{FFFFFFFF} seconds or more. (We do not expect this to ever be used). \\ \hline 255 & Reserved for future expansion & Undefined \\ \hline \end{tabular} \end{center} \footnotetext{You might think that the recipient needs to worry about the IP address of the FORWARD message it sends to the original client being different from that of the original server (the sender of this message). However, this is not the case. The existence of multi-homed hosts means that the sender of a message cannot assume that the IP address of a reply (as recorded in the UDP packet encapsulating the response it receives) is the same as the address the packet was sent to. The sender must use the connection ID to match up sent messages and received replies.} %\end{table} \begin{description} \item[Octets 13 and above] Fields specific to particular flags and options. First, additional data fields specific to the flags in octet 11 should be specified. \item[Next Octets] Additional Address Information (if Additional Address Information flag specified): The first octet specifies the type of additional address information. The next octet specifies the length of the address information, from 0 to 255 octets.\footnote{The entire 255 octets are not available for address information, since they are part of the header, and the maximum header length header is limited to 64 octets.} Its length does not include the two octets that specify type and length. The following octets contain the address information itself, and its format is dependent upon the type of address information. \item[Next 2 octets] Priority (if Priority flag specified): These octets are a signed integer representing the priority of the request. Not all implementations understand this message, and many that do will not honor requests for expedited handling. Negative numbers indicate expedited handling while higher numbers indicate greater delays. A priority of 0 is normal. \item[Next 2 octets] Protocol ID (if Protocol ID flag specified): These octets identify the interpretation of the data carried in the packet. The default, or an explicitly specified value of 0, mean that it is not specified, but has been agreed upon externally (i.e. the applications will know). \item[Next octets] Any data specific to the option set by octet 12 should be specified. This is the data specified in the ``additional fields'' column of the table ``Value of flags for octet 12.'' \end{description} \chapter{Prospero Conventions\label{conventions}} \section{\protect\meta{hsoname}s} There are some special \meta{hsoname}s that the current Prospero server may recognize, if it has been configured appropriately. If an \meta{hsoname} begins with the string \lit{AFTP/}, it is interpreted as a path relative to the anonymous FTP directory on that server. If an \meta{hsoname} begins with the string \lit{GOPHER}\zoos\lit{(}\meta{gopher-port-number}\lit{)}\zooe, it is interpreted to refer to GOPHER data files on that host . If an \meta{hsoname} begins with the string \lit{GOPHER-GW}, it refers to GOPHER data files on another host. If an \meta{hsoname} begins with the string \lit{ARCHIE/}, it represents an Archie database query. \chapter{Prospero Protocol Changes from Version 1 to Version 5} Versions 2, 3, and 4 of the Prospero protocol were not used. The protocol number jumped from version 1 to version 5 to keep the software number and version number consistent; the first version of the server to implement version 5 protocol had a software version number of 5. For now, all Prospero servers continue to accept Version 1 of the protocol. Not all of the protocol changes are listed here. In version 1, the \lit{EDIT-LINK-INFO} command was called \lit{MODIFY-LINK}. The syntax of the arguments has also been changed. The method of specifying attributes to \lit{LIST} has changed. The lines returned from \lit{LIST} are also in a new format. The quoting mechanism has been formalized, and extended to apply to multiple-component directory names. Therefore, the \lit{ONECOMP} option to \lit{LIST} is now officially dead (it was never implemented in any server anyway). Note that no Version 1 server ever implemented quoting properly anyway. Therefore, if a client speaks Version 1 Protocol, it will not be able to access filenames with spaces in them. The \meta{magic-no} field has been replaced with zero or more occurrences of the sequence \lit{ID} \meta{id-type} \meta{id-value}. \lit{GET-OBJECT-INFO} used to have the reserved keyword \lit{ID}, but this has been flushed. The syntax of the arguments of \lit{EDIT-OBJECT-INFO} has been changed, in order to avoid a syntactic amgiguity. Many changes have occurred to the arguments of commands. Filter syntax has changed drastically. Separate principals are now sent as separate protocol tokens in ACL and attribute definitions. The \atr{target} field used to have a possible value of \lit{SYM-LINK}. This has been changed to \lit{SYMBOLIC}. The \atr{base-type} field has been introduced. The syntax of a \meta{target} of \lit{EXTERNAL} has changed radically. EXTERNAL links now look a lot more like conventional links. The meaning of the \atr{access-method} attribute has changed radically; it's now a lot more flexible. Support for Kerberos has been specified. \end{document} 
(.txt)